fix(wrapper): stop Wrap mutating the ingress it is given - #84

Found while reviewing the abandoned claude/implement-wrapper-improvements-* branch (thorwhalen/priv#38). That branch turned out to be already merged by another route — its only remaining difference from master is quote style. But reviewing it surfaced a real bug in the code that did land.

The bug

preserve_signature wrote __signature__ and __annotations__ onto the ingress object. A decorator normally defines one ingress and reuses it for every function it wraps, so that write corrupts the caller's function — and every later Wrap built from the same ingress:

def shared_ingress(*args, **kwargs): return args, kwargs
def f(a: int) -> int: ...
def g(x: str, y: str) -> str: ...

Wrap(f, ingress=shared_ingress)
signature(shared_ingress)             # (a: int) -> int      <- caller's function MUTATED
Sig(Wrap(g, ingress=shared_ingress))  # (a: int) -> str      <- WRONG

Wrap(g, ...) still executes correctly (w2('a','b') == 'ab'), so nothing ever surfaced the lie. That is the worst shape this bug could take in this package: silently wrong in exactly the introspection i2 exists to provide, and meshed builds its DAGs from these signatures.

The fix

Preserving means the wrapper presents func's interface — so read the signature from func, and never write it onto the ingress. Defaults are now read from the same source as the signature, so the two can't disagree.

Cleanups in the same area

• _get_return_annotation had x if x is not Parameter.empty else empty three times. empty is Parameter.empty, so each was a no-op around a duplicated fallback. Now one rule — egress wins if annotated, else func — with doctests covering the case that made the dead branch look meaningful: an unannotated func yields empty, not None, since None is a real annotation meaning "returns None".
• Extracted _is_generic_signature (the predicate 'auto' actually turns on), with doctests for the near-misses: (*a) alone, (x, *a, **kw).
• Dropped the unused func parameter from _should_preserve_signature.
• Named the 'auto' sentinel AUTO_PRESERVE_SIGNATURE so it has one definition.
• Converted the numpydoc docstrings to the :param: style used elsewhere in this module.

Public API unchanged.

Verification

• The three regression tests fail on the old code and pass on the new — verified by stashing the fix.
• i2: 470 passed, 2 xfailed.
• meshed (biggest dependent): 60 passed.
• Swept every local package importing i2.wrapper: extrude, front, larder, oa pass; crude and o fail identically with and without this change (selenium, missing hum.sound) — pre-existing.
• Zero new ruff findings (732 before and after).

Two hunks in the diff are ruff reformatting untouched assert statements — the publish job runs ruff format . and pushes back anyway, so they'd land regardless.

https://claude.ai/code/session_01GsUw8ey8KikzNFQ1UaWWia